gtktreesortable: Move documentation to inline comments

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 66a28214a31708689f395e82fa4feb65382fc98a..40585283d5b62d04d7bd503dc03b86cb74bf9f52 100644 (file)
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -50,6 +50,7 @@ gtktoolbar.sgml
 gtktoolitem.sgml
 gtktooltip.sgml
 gtktreednd.sgml
+gtktreesortable.sgml
 gtktreestore.sgml
 gtktreeviewcolumn.sgml
 gtktypeutils.sgml

diff --git a/docs/reference/gtk/tmpl/gtktreesortable.sgml b/docs/reference/gtk/tmpl/gtktreesortable.sgml
deleted file mode 100644 (file)
index f5ebb8f..0000000
--- a/docs/reference/gtk/tmpl/gtktreesortable.sgml
+++ /dev/null
@@ -1,135 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkTreeSortable
-
-<!-- ##### SECTION Short_Description ##### -->
-The interface for sortable models used by GtkTreeView
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-#GtkTreeSortable is an interface to be implemented by tree models which
-support sorting. The #GtkTreeView uses the methods provided by this interface
-to sort the model.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GtkTreeModel, #GtkTreeView
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkTreeSortable ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL GtkTreeSortable::sort-column-changed ##### -->
-<para>
-
-</para>
-
-@treesortable: the object which received the signal.
-
-<!-- ##### STRUCT GtkTreeSortableIface ##### -->
-<para>
-
-</para>
-
-@g_iface: 
-@sort_column_changed: 
-@get_sort_column_id: 
-@set_sort_column_id: 
-@set_sort_func: 
-@set_default_sort_func: 
-@has_default_sort_func: 
-
-<!-- ##### USER_FUNCTION GtkTreeIterCompareFunc ##### -->
-<para>
-A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive
-integer if @a sorts before @b, @a sorts with @b, or @a sorts after @b
-respectively. If two iters compare as equal, their order in the sorted model 
-is undefined. In order to ensure that the #GtkTreeSortable behaves as 
-expected, the GtkTreeIterCompareFunc must define a partial order on 
-the model, i.e. it must be reflexive, antisymmetric and transitive.
-</para>
-<para>
-For example, if @model is a product catalogue, then a compare function
-for the "price" column could be one which returns 
-<literal>price_of(@a) - price_of(@b)</literal>.
-</para>
-
-@model: The #GtkTreeModel the comparison is within
-@a: A #GtkTreeIter in @model
-@b: Another #GtkTreeIter in @model
-@user_data: Data passed when the compare func is assigned e.g. by
-gtk_tree_sortable_set_sort_func()
-@Returns: a negative integer, zero or a positive integer depending on whether
-    @a sorts before, with or after @b
-
-
-<!-- ##### FUNCTION gtk_tree_sortable_sort_column_changed ##### -->
-<para>
-
-</para>
-
-@sortable: 
-
-
-<!-- ##### FUNCTION gtk_tree_sortable_get_sort_column_id ##### -->
-<para>
-
-</para>
-
-@sortable: 
-@sort_column_id: 
-@order: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_tree_sortable_set_sort_column_id ##### -->
-<para>
-
-</para>
-
-@sortable: 
-@sort_column_id: 
-@order: 
-
-
-<!-- ##### FUNCTION gtk_tree_sortable_set_sort_func ##### -->
-<para>
-
-</para>
-
-@sortable: 
-@sort_column_id: 
-@sort_func: 
-@user_data: 
-@destroy: 
-
-
-<!-- ##### FUNCTION gtk_tree_sortable_set_default_sort_func ##### -->
-<para>
-
-</para>
-
-@sortable: 
-@sort_func: 
-@user_data: 
-@destroy: 
-
-
-<!-- ##### FUNCTION gtk_tree_sortable_has_default_sort_func ##### -->
-<para>
-
-</para>
-
-@sortable: 
-@Returns: 
-
-

diff --git a/gtk/gtktreesortable.c b/gtk/gtktreesortable.c
index b699f1eca39b798a90263367280044b8579b6bcd..75f7e3c66e4f37c4b26aa505ee7671ab52ea480d 100644 (file)
--- a/gtk/gtktreesortable.c
+++ b/gtk/gtktreesortable.c
@@ -24,6 +24,18 @@
 #include "gtkintl.h"
 
 
+/**
+ * SECTION:gtktreesortable
+ * @Short_description: The interface for sortable models used by GtkTreeView
+ * @Title: GtkTreeSortable
+ * @See_also:#GtkTreeModel, #GtkTreeView
+ *
+ * #GtkTreeSortable is an interface to be implemented by tree models which
+ * support sorting. The #GtkTreeView uses the methods provided by this interface
+ * to sort the model.
+ */
+
+
 static void gtk_tree_sortable_base_init (gpointer g_class);
 
 GType

diff --git a/gtk/gtktreesortable.h b/gtk/gtktreesortable.h
index 4931276d980254fb3b0f2dc259bab193dfee0fcd..c9ce6e787a34bb1a9f7bbd7548aebf36878a407f 100644 (file)
--- a/gtk/gtktreesortable.h
+++ b/gtk/gtktreesortable.h
@@ -46,6 +46,28 @@ enum {
 typedef struct _GtkTreeSortable      GtkTreeSortable; /* Dummy typedef */
 typedef struct _GtkTreeSortableIface GtkTreeSortableIface;
 
+/**
+ * GtkTreeIterCompareFunc:
+ * @model: The #GtkTreeModel the comparison is within
+ * @a: A #GtkTreeIter in @model
+ * @b: Another #GtkTreeIter in @model
+ * @user_data: Data passed when the compare func is assigned e.g. by
+ *  gtk_tree_sortable_set_sort_func()
+ *
+ * A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive
+ * integer if @a sorts before @b, @a sorts with @b, or @a sorts after @b
+ * respectively. If two iters compare as equal, their order in the sorted model
+ * is undefined. In order to ensure that the #GtkTreeSortable behaves as
+ * expected, the GtkTreeIterCompareFunc must define a partial order on
+ * the model, i.e. it must be reflexive, antisymmetric and transitive.
+ *
+ * For example, if @model is a product catalogue, then a compare function
+ * for the "price" column could be one which returns
+ * <literal>price_of(@a) - price_of(@b)</literal>.
+ *
+ * Returns: a negative integer, zero or a positive integer depending on whether
+ *   @a sorts before, with or after @b
+ */
 typedef gint (* GtkTreeIterCompareFunc) (GtkTreeModel *model,
                                         GtkTreeIter  *a,
                                         GtkTreeIter  *b,